Why is it important to decide on vector dimensionality and distance metric carefully before going to production, rather than treating them as easy-to-change settings?

Vector dimensionality and distance metric are properties of the vector space itself, not tunable parameters. The dimensionality is determined by the embedding model - a model that outputs 768-dim vectors cannot produce 1536-dim vectors, and a collection created for 768 cannot store 1536-dim vectors. The distance metric determines how similarity is defined, and it affects the neighbor relationships in the HNSW graph: two points that are nearest under cosine may not be nearest under Euclidean. Changing either means the existing vectors are no longer valid for the new configuration, so you must re-embed all data with a model that produces the new dimensionality and rebuild the index with the new metric. There is no in-place migration of the vector space. This is why these decisions must be made carefully up front - they are not like changing an optimizer threshold or a quantization setting, which can be adjusted without re-embedding.

The mechanism behind the immutability is that the index and the storage layout encode the dimensionality and the metric. The HNSW graph's node layout depends on the vector size: each node stores the vector (or a quantized version of it) and the edge list, and the size of the node is determined by the dimension. The distance function is used during graph construction to compute similarity, and the graph's structure reflects the metric's ordering. A graph built with cosine is not a valid graph for Euclidean because the neighbor relationships differ. Qdrant enforces this at the collection level: create_collection requires the size and distance, and there is no update_collection call that changes either. If you try to upsert a vector of the wrong size, Qdrant returns a dimension-mismatch error rather than silently corrupting the index. The practical consequence is that a model upgrade is a migration project, not a config change: you create a new collection with the new size and metric, re-embed all source data with the new model, upsert the new vectors, and cut over via an alias once the new collection is fully populated and validated.

The trade-off is between the cost of a careful up-front decision and the cost of a migration later. Getting the dimensionality and metric right up front requires understanding the embedding model's output, the intended similarity semantics, and the cost profile (higher dimensions cost more memory and latency). Getting it wrong later costs a full re-embedding and reindexing, which for a large collection can take days and requires a migration strategy. The common mistake is to choose the distance metric by default (cosine for everything) without checking the model's training objective - models trained with dot-product loss expect dot product, and using cosine changes the ranking because it normalizes vectors. The second mistake is to pick a high-dimension model without considering the memory and latency cost, then discover that the deployment does not fit. The third mistake is to assume you can change the metric later by re-normalizing vectors - you cannot, because the graph structure encodes the metric. The fourth mistake is to mix vectors from different models in the same collection during a migration, which produces a mix of representations that no single query can rank correctly. Version note: the set of supported distance metrics and the constraints on them (especially with quantization or multivector fields) have evolved across Qdrant releases. Verify the supported combinations on your version before designing a collection.

Version-dependent: the aliases API and the collection creation API have been stable across recent releases, but the exact shape of the create_alias operation and the supported distance metrics have evolved. The migration pattern (new collection, re-embed, validate, alias cutover) is the standard approach regardless of version. For multi-vector collections, a migration may affect only some named vectors, which changes the complexity of the migration.